Amiga Format CD 32/Amiga Format AFCD32 (Nov 1998, Issue 117).iso/-seriously_amiga-/programming/c/mesa-2.6/readme.amiga

Text File | 1998-08-10 | 12KB | 338 lines

                             AmigaMesaRTL 1.0
                      A run-time library of Mesa 2.6

                         by Jarno van der Linden
                            [e-mail]

             Mesa 2.6 is Copyright (C) 1995-1998  Brian Paul


INTRODUCTION
============

Once upon a time there was an Amiga port of Mesa by Stefan Zivkovic.
However, just as this port became interesting, Stefan could no longer
support it.

Then came CyberGL. A run-time library, which ran reasonably comfortably
even on lower-end machines with AGA. Unfortunately, it only implemented a
subset of OpenGL. Furthermore, the output even on a 256 colour AGA screen
was far from impressive. At present, development seems to have stalled
(possibly pending the release of the CV-PPC and BVision cards).

Back to Mesa, through H&P we've seen the release of StormMesa.
Unfortunately this too comes in the form of a link library.

So I set out to create my own driver with the following objectives:

    - Based on the latest release of Mesa
    - Should come in the form of a run-time library
    - Reasonable speed on an 50MHz '030/'881 system
    - Good quality output on AGA

With AmigaMesaRTL, I think I have achieved these goals. Of course, don't
expect miracles. Framerates are still better counted in seconds-per-frame
rather than frames-per-second on my machine (A1200, Blizzard1230IV, 50MHz
'030/'881, 32MB fast). But it is still faster than CyberGL and the output
is a significantly better.



THEORY OF OPERATION
===================

The driver (amigamesertl.c) does all reading from and writing to a simple
memory buffer. This buffer is made up out of single bytes in the case of
colour index mode, and 4 bytes in the case RGB or RGBA mode.

When glFlush() is called, the buffer is written to the window using a
quantization library. In index mode, the default quantizer calls
WritePixelArray8(). In RGB mode, the buffer is first passed to a colour
quantization algorithm. The resulting palette is loaded with LoadRGB32(),
and the quantized buffer is written to the window with WritePixelArray8().

The quantizer is a slightly modified version of DL1 from a package by
Dennis Lee ([e-mail]). I've included the original
documentation in the amiga/quantizers/dl1 directory.

Because of the various buffers involved, AmigaMesaRTL does use a fair bit
of memory. But the output is about as good as it can get in 256 colours,
and as all the drawing is done off-screen most of the AGA speed bottleneck
is avoided.



COMPILING THE LIBRARY
=====================

The AmigaMesaRTL distribution only contains the changed and new files of
Mesa. You will need the Mesa 2.6 distribution. Once you have obtained the
Mesa 2.6 distribution and unpacked it to somewhere, copy the amiga
directory of AmigaMesaRTL to the Mesa directory. Go to the amiga/src
directory, change the SCOPTIONS file to suit your system (mainly the MATH
and CPU settings), and run SMake. Sit back, relax, enjoy life. This is
going to take a while.

Note that there are still a few references to __XCEXIT(). Just ignore it
and let the linker replace it with __stub().

Once this is done, you should end up with a file called mesa.library in
the amiga/library directory.

Next, go to the amiga/lib directory, edit the SCOPTIONS file if you want
to, run SMake. Out should come Mesa.LIB.

Finally, compile a quantizer library. For dl1, go to amiga/quantizers/dl1
and run SMake. A library called "dl1" (note no ".library") should appear
in amiga/library/quantizers.

That is all that is needed to get a working mesa library.



USING THE LIBRARY
=================

To compile a program using AmigaMesaRTL, make sure the compiler can see
the files in amiga/include and the link libraries in amiga/lib (by e.g.
adding them to your INCLUDE: tree).

Mesa.LIB contains autoopen code for the mesa.library, so you shouldn't
have to worry about opening and closing it. Just don't forget to link with
Mesa.LIB.

Once you have set up your screen and window as per normal, call
AmigaMesaRTLCreateContext() to create a new rendering context for the
window. Make sure it is current by calling AmigaMesaRTLMakeCurrent().

Do lots of interesting graphics stuff. Don't forget that glFlush() has to
be called (directly or indirectly) for the result to appear in the window.

Before closing the window, you should destroy the context with
AmigaMesaRTLDestroyContext().

See the included examples for inspiration..

Tags
----

AmigaMesaRTLCreateContext() and AmigaMesaRTLCreateContextA() understand
the following tags:

  Tag Name    : AMRTL_RGBAMode
  Values      : TRUE | FALSE
  Default     : TRUE
  Description : Use RGBA colour if TRUE, index colours if FALSE

  Tag Name    : AMRTL_IndexMode
  Values      : TRUE | FALSE
  Default     : FALSE
  Description : Use index colours if TRUE, RGBA colour if FALSE

  Tag Name    : AMRTL_NumColours
  Values      : 2...256
  Default     : 256
  Descrption  : Number of colours to allocate

  Tag Name    : AMRTL_NumColors
  Description : To keep our American friends happy

  Tag Name    : AMRTL_ColourBase
  Values      : 0...254
  Default     : 0
  Description : Palette index of the first colour

  Tag Name    : AMRTL_ColorBase
  Description : More Americana

  Tag Name    : AMRTL_Quantizer
  Values      : A string
  Default     : Content of environment variable AmigaMesaRTL/Quantizer
              : or the value "dl1" if not set
  Description : Name of quantizer to use

  Tag Name    : AMRTL_QuantizerVersion
  Values      : Any ULONG
  Default     : Content of env. variable AmigaMesaRTL/QuantizerVersion
              : or 0 if not set
  Description : Minimum library version of quantizer to use


GLUT
====

Having a Mesa library is all fine and dandy, but most Mesa and OpenGL
examples use the GL Utility Toolkit (GLUT) by Mark Kilgard. So the obvious
answer is: we need a port of GLUT.

Having looked at the GLUT source code, this is easier said than done. It
is highly X11-centric, with a Windows port mixed in. I thought about it,
but in the end I decided to do a from-scratch GLUT look-alike
implementation. It can be found in amiga/src-glut.

At present, most of the most-commonly used functions are implemented. No
guarantee that they behave identically to the official GLUT distribution,
but most of the redbook examples seem to work OK.

Compiling GLUT
--------------

To compile the GLUT library, go to the amiga/src-glut directory, set up
the SCOPTIONS file to your liking, run SMake, and hey-presto! out comes
amiga/lib/GLUT.LIB.

Using GLUT
----------

when compiling a GLUT program, make sure you link with GLUT.LIB and
Mesa.LIB.

When run, a glut program will by default try to open a window on a public
screen named Mesa. Use one of the zillion pubscreen managers available on
AmiNet to set one up.

GLUT Menus
..........
The GLUT menus use the usual Amiga menu system. Instead of having a menu
associated with a mouse button, there is a "Left Menu", "Middle Menu", and
"Right Menu" menu.
As the Amiga menu system only supports up to one level of sub-menus, any
sub-sub-menus (and sub-sub-sub-menus and sub-sub-sub-sub-menus and ...)
will be changed to a sub-menu after the parent.

GLUT mouse buttons
..................
As the right mouse button is tied up with menus, middle and right mouse
button presses can be done by qualifying the left mouse button press with
the Right-Amiga and Right-Alt keys respectively. For those of you with
three-button mice, the middle button should also be recognised.

GLUT termination
................
The GLUT main loop is traditionally terminated by exit()'ing the program.
Amiga GLUT uses SAS/C's STI_ and STD_ mechanism to clean up on exit().
Quiting a GLUT program is usually done by pressing the ESC key. Clicking
the window close button will cause Amiga GLUT to call the context's
keyboard function with an ESC key code.
However, some example programs never exit. Instead they expect the user to
kill the program (by e.g. ^C). To handle such evil programs, Amiga GLUT
has a panic drop-through. If pressing the window close button has no
effect (i.e. the program is not listening to ESC key presses), a second
click on the window close button will cause glutMainLoop() to return. This
usually works as glutMainLoop() is often the last command in main() before
it returns. But, as this is against the documented behaviour of
glutMainLoop(), Bad Things may happen instead.

GLUT keys
.........
The GLUT special keys implemented are: the cursor keys, and functon keys
F1 to F10.

Idle
....
A single glutMainLoop() loop will handle all the messages on the queue. If
set, glutIdleFunc() will be called whenever glutMainLoop() finds no
messages to handle (other than IDCMP_INTUITICKS) in a single loop. (This
is in contrast to a macintosh implementation I know of which actually
speeds up if you e.g. press a key).

Running a GLUT program
----------------------

Any GLUT program which calls glutInit() (as all should), recognise the
following command line options:

  Option      : -numcolours
  Values      : 2...256
  Default     : 248
  Description : Set value for AMRTL_NumColours

  Option      : -numcolors
  Description : Americana

  Option      : -colourbase
  Values      : 0...254
  Default     : 8
  Description : Set value for AMRTL_ColourBase

  Option      : -colorbase
  Description : Americana

  Option      : -pubscreen
  Values      : <any name>
  Default     : MESA
  Description : Set the public screen to open windows on

  Option      : -quantizer
  Values      : <any name>
  Default     : <not set>
  Description : Set value for AMRTL_Quantizer

  Option      : -quantizerversion
  Values      : <any ULONG>
  Default     : <not set>
  Description : Set value for AMRTL_QuantizerVersion

So for example, to get some interesting things going on the same screen
without the colours interfering:
  run bounce -colourbase 8 -numcolors 4
  run gears -colourbase 12 -numcolors 64
  run isosurf -va -colourbase 76 -numcolors 88
  run fog -colourbase 164 -numcolors 92

If a program doesn't appear to give any output, check to see if it calls
glFlush(), or anything that calls it (like glutSwapBuffers()). If it
doesn't, add it (typically at the end of the display() function). Also
make sure you give the program plenty of stack.


WARNING!
--------

Please beware that at present, Amiga GLUT lacks a lot of error checking.
Bad Things will very likely happen if Something Goes Wrong.


Quantizer Plugins
=================

Since version 1.1, AmigaMesaRTL has a plugin system for quantizers. They
are actually just libraries. Which quantizer library to use is determined
by the environment variables "AmigaMesaRTL/Quantizer" and
"AmigaMesaRTL/QuantizerVersion". If they are not set, the defaults are
"dl1" and "0" respectively. The AMRTL_Quantizer and AMRTL_QuantizerVersion
tags, and matching glutInit() arguments, overide these.

The quantizers are expected to be found in the "libs:quantizers/"
directory.


Writing your own quantizer
--------------------------

The quantizer API is documented in amiga/quantizers/quantizer.doc and the
.fd file is amiga/libraries/quantizers/quantizer.fd. See the dl1 quantizer
source for an example implementation. If there is something you would like
to see added to the interface, tell me. Particularly I would like to know
if ARGB is more convenient than RGBA.


FUTURE
======

Mesa 3.0 will shortly emerge from beta state. It shouldn't take long for
me update the library to it when it does.

Better colour management. At present, no locking is done, and multiple
windows of the same GLUT instance will share the same palette indices.

Fix the zillions of bugs everyone but me will no doubt find.

Maybe an RTG option. I don't have access to a graphics board, and when P5
comes out with their PPC graphics boards, this whole library might be
obsolete.

Change GLUT to a run-time library.